home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 October / EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso / Aminet / dev / cross / dasm202.lha / dasm-2.02 / DASM.DOC < prev    next >
Text File  |  1995-03-02  |  20KB  |  603 lines
  1.  
  2.  
  3. DOCUMENTATION FOR DASM V2.0, a high level macro cross assembler for:
  4.  
  5.     -6502
  6.     -68705
  7.     -6803
  8.     -HD6303 (extension of 6803)
  9.  
  10.     Soon will work for 68HC11 (next ver)
  11.  
  12.     (C)Copyright 1987,1988 Matthew Dillon, All Rights Reserved
  13.  
  14.     Publicly distributable for non-profit only.  Must be distributed
  15.     as is, with NO CHANGES to the documentation or code.   Over the last
  16.     year my work has included writing software to drive small single-chip
  17.     microcomputers for various things (remote telemetry units, for
  18.     instance).    I have had need to program quite a few different processors
  19.     over that time.
  20. #if Olaf
  21.     If you #define various OlafXXX to 1, then some changes will be
  22.     introduced.
  23. #endif
  24.  
  25.     At the beginning, I used an awful macro assembler running on an IBM-PC.
  26.     I *really* wanted to do it on my Amiga.  Thus the writing of this
  27.     program.
  28.  
  29.     Feel free to suggest other similar processors for me to add to the list!
  30.     The processor type is specified with a pseudo-op (see below).  This
  31.     assembler produces only binary output in one of three formats described
  32.     below.  In general, one has a master assembly file which INCLUDEs all
  33.     the modules.
  34.  
  35.     Also provided is FTOHEX which converts an output file in one of the
  36.     three formats to an intel-hex format suitable for many intelligent
  37.     prom programmers (I have a GTEK).
  38.  
  39.     YES it's packed with features!
  40.  
  41. COMMAND LINE:
  42.  
  43.     asm srcfile [options]
  44.  
  45.     options:    -f#     select output format 1-3 (default 1, see below)
  46.             -oname  select output file name (else a.out)
  47.             -lname  select list file name   (else none generated)
  48.             -sname  select symbol dump file (else none generated)
  49.             -v#     select verboseness 0-4 (default 0, see below)
  50.             -d        debug mode
  51.             -DSYMBOL            predefine a symbol, set to 0
  52.             -DSYMBOL=EXPRESSION     predefine a symbol, set to exp
  53. #if OlafM
  54.             -Mname=exp     define label as in EQM
  55. #endif
  56. #if OlafLt
  57.             -<         Swap < and > (to be backwards compatible)
  58. #endif
  59.  
  60.     Note: file names should be in RAM: for speed.  If a list file is
  61.     specified, it should be in the RAM: disk (assembly is slowed down
  62.     quite a bit anyway).
  63.  
  64.     Example:    asm master.asm -f2 -oram:out -lram:list -v3 -DVER=4
  65.  
  66. FORMAT OPTIONS:
  67.  
  68.     1  (DEFAULT)
  69.  
  70.     The output file contains a two byte origin in LSB,MSB order, then
  71.     data until the end of the file.
  72.  
  73.     Restrictions:    Any instructions which generate output (within an
  74.     initialized segment) must do so with an ascending PC.  Initialized
  75.     segments must occur in ascending order.
  76.  
  77.     2  RAS (Random Access Segment)
  78.  
  79.     The output file contains one or more hunks.  Each hunk consists
  80.     of a 2 byte origin (LSB,MSB), 2 byte length (LSB,MSB), and that
  81.     number of data bytes.  The hunks occur in the same order as
  82.     initialized segments in the assembly.  There are no restrictions
  83.     to segment ordering.  The next hunk begins after the previous
  84.     hunk's data, until the end of the file.
  85.  
  86.     3  RAW (Raw)
  87.  
  88.     The output file contains data only (format #1 without the 2 byte
  89.     header).  Restrictions are the same as for format #1.
  90.  
  91.     Format 3    RAW (Raw format)
  92.         Same as format 1, but NO header origin is generated.  You get
  93.         nothing but data.
  94.  
  95. VERBOSE OPTIONS:
  96.  
  97.     0    (default)
  98.  
  99.     Only warnings and errors are generated
  100.  
  101.     1
  102.     -Segment list information generated after each pass
  103.     -Include file names are displayed
  104.     -statistics on why the assembler is going to make another pass
  105.         R1,R2 reason code: R3
  106.         where R1 is the number of times the assembler encountered
  107.         something requiring another pass to resolve.  R2 is the
  108.         number of references to unknown symbols which occured in the
  109.         pass (but only R1 determines the need for another pass).  R3
  110.         is a BITMASK of the reasons why another pass is required.
  111.         See the end of this document for bit designations.
  112.  
  113.     2
  114.     mismatches between program labels and equates are displayed
  115.     on every pass (usually none occur in the first pass unless you
  116.     have re-declared a symbol name).
  117.  
  118.     displayed information for symbols:
  119.         ???? = unknown value
  120.         str  = symbol is a string
  121.         eqm  = symbol is an eqm macro
  122.         (r)  = symbol has been referenced
  123.         (s)  = symbol created with SET or EQM pseudo-op
  124.  
  125.     3
  126.         Unresolved and unreferenced symbols are displayed every pass
  127.         (unsorted, sorry)
  128.  
  129.     4
  130.         An entire symbol list is displayed every pass to STDOUT.
  131.         (unsorted, sorry)
  132.  
  133. PROCESSOR MODEL:
  134.  
  135.     The processor model is chosen with the PROCESSOR pseudo-op and should
  136.     be the first thing you do in your assembly file.   Different processor
  137.     models use different integer formats (see below).  The word order does
  138.     not effect the headers in the output files (-f1 and -f2), which are
  139.     always LSB,MSB.  The word ordering effects all address, word, and
  140.     long generation.
  141.  
  142.     Only one PROCESSOR pseudo-op may be declared in the entire assembly,
  143.     and should be the first thing encountered.
  144.  
  145.     -6502        LSB,MSB
  146.     -68HC11     MSB,LSB (next release)
  147.     -68705        MSB,LSB
  148.     -6803        MSB,LSB
  149.     -HD6303     MSB,LSB
  150.  
  151. SEGMENTS:
  152.     The SEG pseudo-op creates/sets the current segment.  Each segment has
  153.     it's own origin and is optionally an 'uninitialized' segment.
  154.     Unitialized segments produce no output and have no restrictions.  This
  155.     is useful for determining the size of a certain assembly sequence
  156.     without generating code, and for assigning RAM to labels.
  157.  
  158. GENERAL:
  159.     Most everything is recursive.  You cannot have a macro DEFINITION
  160.     within a macro definition, but can nest macro calls, repeat loops,
  161.     and include files.
  162.  
  163.     The other major feature in this assembler is the SUBROUTINE pseudo-op,
  164.     which logically separates local labels (starting with a dot).  This
  165.     allows you to reuse label names (for example, .1 .fail) rather than
  166.     think up crazy combinations of the current subroutine to keep it all
  167.     unique.
  168.  
  169.     Almost nothing need be resolved in pass 1.    The assembler will make
  170.     multiple passes in an attempt to resolve the assembly (including just
  171.     one pass if everything is resolved immediately).
  172.  
  173.  
  174. PSEUDOPS:
  175.  
  176.     INCLUDE     "name"
  177.  
  178.         Include another assembly file.
  179.  
  180. [label] SEG[.U]     name
  181.  
  182.         This sets the current segment, creating it if neccessary.  If
  183.         a .U extension is specified on segment creation, the segment
  184.         is an UNINITIALIZED segment.  The .U is not needed when going
  185.         back to an already created uninitialized segment, though it
  186.         makes the code more readable.
  187.  
  188. [label] DC[.BWL]    exp,exp,exp ...
  189.  
  190.         Declare data in the current segment.  No output is generated if
  191.         within a .U segment.  Note that the byte ordering for the
  192.         selected processor is used for each entry.
  193.  
  194.         The default size extension is a byte.
  195. #if OlafByte
  196.         BYTE, WORD and LONG are synonyms for DC.B, DC.W and DC.L.
  197. #endif
  198.  
  199. [label] DS[.BWL]    exp[,filler]
  200.  
  201.         declare space (default filler is 0). Data is not generated if
  202.         within an uninitialized segment.  Note that the number of bytes
  203.         generated is exp * entrysize (1,2, or 4)
  204.  
  205.         The default size extension is a byte.
  206.  
  207. [label] DV[.BWL]    eqmlabel exp,exp,exp....
  208.  
  209.         This is equivalent to DC, but each exp in the list is passed
  210.         through the symbolic expression specified by the EQM label.
  211.         The expression is held in a special symbol dotdot '..' on each
  212.         call to the EQM label.
  213.  
  214.         See EQM below
  215.  
  216. [label] HEX        hh hh hh..
  217.  
  218.         This sets down raw HEX data.  Spaces are optional between bytes.
  219.         NO EXPRESSIONS are allowed.  Note that you do NOT place a $
  220.         in front of the digits.  This is a short form for creating
  221.         tables compactly.  Data is always layed down on a byte-by-byte
  222.         basis.
  223.  
  224.         Example:        HEX 1A45 45 13254F 3E12
  225.  
  226.     ERR
  227.  
  228.         Abort assembly.
  229.  
  230. [label] ORG        exp[,DefaultFillVal]
  231.  
  232.         This pseudop sets the current origin.  You can also set the
  233.         default fill character (a byte value) with this pseudoop.  NOTE
  234.         that no filler is generated until the first data-generating
  235.         opcode/psueoop is encountered after this one.  Sequences like:
  236.  
  237.         org  0,255
  238.         org  100,0
  239.         org  200
  240.         dc   23
  241.  
  242.         will result in 200 zero's and a 23.  Use DS or ALIGN to
  243.         specifically generate data output.    This allows you to specify
  244.         some ORG, then change your mind and specify some other (lower
  245.         address) ORG without causing an error (assuming nothing is
  246.         generated inbetween).
  247.  
  248. [label] RORG        exp
  249.  
  250.         This activates the relocatable origin.  All generated
  251.         addresses, including '.', although physically placed at the
  252.         true origin, will use values from the relocatable origin.
  253.         While in effect both the physical origin and relocatable origin
  254.         are updated.
  255.  
  256.         The relocatable origin can skip around (no limitations).  The
  257.         relocatable origin is a function of the segment.  That is, you
  258.         can still SEG to another segment that does not have a
  259.         relocatable origin activated, do other (independant) stuff
  260.         there, and then switch back to the current segment and continue
  261.         where you left off.
  262.  
  263.     PROCESSOR model
  264.  
  265.         do not quote.  model is one of: 6502,6803,HD6303,68705,68HC11
  266.         Can only be executed once, and should be the first thing
  267.         encountered by the assembler.  the 68HC11 will be available
  268.         next release.
  269.  
  270.     ECHO exp,exp,exp
  271.  
  272.         The expressions (which may also be strings), are echod on the
  273.         screen and into the list file
  274.  
  275. [label] REND
  276.  
  277.         Deactivate the relocatable origin for the current segment.
  278.         Generation uses the real origin for reference.
  279.  
  280. [label] ALIGN        N[,fill]
  281.  
  282.         Align the current PC to an N byte boundry.    The default
  283.         fill character is 0.
  284.  
  285. [label] SUBROUTINE  name
  286.  
  287.         This isn't really a subroutine, but a boundry between sets of
  288.         temporary labels (which begin with a dot).    Temporary label
  289.         names are unique within segments of code bounded by SUBROUTINE:
  290.  
  291.         CHARLIE subroutine
  292.             ldx #10
  293.         .1    dex
  294.             bne .1
  295.         BEN    subroutine
  296.             ldx #20
  297.         .1    dex
  298.             bne .1
  299.  
  300. symbol    EQU        exp
  301. #if OlafAsgn
  302. symbol    =        exp
  303. #endif
  304.  
  305.         The expression is evaluated and the result assigned to the
  306.         symbol.
  307.  
  308. symbol    EQM        exp
  309.  
  310.         The STRING representing the expression is assigned to the
  311.         symbol. Occurances of the label in later expressions causes the
  312.         string to be evaluated for each occurance.    Also used in
  313.         conjuction with the DV psuedo-op.
  314.  
  315. symbol    SET        exp
  316.  
  317.         Same as EQU, but the symbol may be reassigned later.
  318.  
  319.     MAC        name
  320.  
  321.         Declare a macro.  lines between MAC and ENDM are the macro.
  322.         You cannot recursively declare a macro.  You CAN recursively
  323.         use a macro (reference a macro in a macro).  No label is
  324.         allowed to the left of MAC or ENDM.
  325.  
  326.  
  327.         Arguments passed to macros are referenced with: {#}.  The first
  328.         argument passed to a macro would thus be {1}.  You should
  329.         always use LOCAL labels (.name) inside macros which you use
  330.         more than once. {0} represents an EXACT substitution of the
  331.         ENTIRE argument line.
  332.  
  333.     ENDM
  334.  
  335.         end of macro def.  NO LABEL ALLOWED ON THE LEFT!
  336.  
  337.     MEXIT
  338.  
  339.         Used in conjuction with conditionals.  Exits the current macro
  340.         level.
  341.  
  342. [label] IFCONST     exp
  343.  
  344.         Is TRUE if the expression result is defined.  No error is
  345.         generated if the expression is undefined.  Is FALSE otherwise.
  346.  
  347. [label] IFNCONST    exp
  348.  
  349.         Is TRUE if the expression result is undefined.  No error is
  350.         generated if the expression is undefined.  Is FALSE otherwise.
  351.  
  352. [label] IF        exp
  353.  
  354.         Is TRUE if the expression result is defined AND non-zero.
  355.         Is FALSE if the expression result is defined AND zero.
  356.         Neither IF or ELSE will be executed if the expression result
  357.         is undefined.
  358.  
  359. [label] ELSE
  360.  
  361.         ELSE the current IF.
  362.  
  363. [label] ENDIF
  364. [label] EIF
  365.  
  366.         Terminate an IF. ENDIF and EIF are equivalent.
  367.  
  368. [label] REPEAT        exp
  369. [label] REPEND
  370.  
  371.         Repeat code between REPEAT/REPEND 'exp' times.  if exp == 0,
  372.         the code repeats forever.  exp is evaluated once.
  373.  
  374.         Y   SET     0
  375.             REPEAT  10
  376.         X   SET     0
  377.             REPEAT  10
  378.             DC        X,Y
  379.         X   SET     X + 1
  380.             REPEND
  381.         Y   SET     Y + 1
  382.             REPEND
  383.  
  384.         generates an output table:    0,0 1,0 2,0 ... 9,0  0,1 1,1 2,1
  385.         ... 9,1, etc...
  386.  
  387.         Labels within a REPEAT/REPEND should be temporary labels with a
  388.         SUBROUTINE pseudoop to keep them unique.
  389.  
  390.         The Label to the left of REPEND is assigned AFTER the loop
  391.         FINISHES.
  392.  
  393.  
  394. [label] XXX[.force] operand
  395.  
  396.         XXX is some mnemonic, not necessarily three characters long.
  397.         The .FORCE optional extension is used to force specific
  398.         addressing modes (see below).
  399.  
  400. [label]    LIST ON or OFF
  401.  
  402.         Turns listing on or off, starting with the current line.
  403.         The effect is local to the current macro or included file.
  404.  
  405. #if OlafDotop
  406.     All pseudo-ops (and incidentally also the mnemonics) can be
  407.     prefixed with a . for compatibility with other assemblers.
  408.     So .IF is the same as IF. This works only because lone .FORCE
  409.     extensions are meaningless.
  410. #endif
  411. #if OlafFreeFormat
  412.     The format of each input line is free: first all leading
  413.     spaces are discarded, and the first word is examined. If it
  414.     does not look like a directive or opcode (as known at that point),
  415.     it is taken as a label. This is sort-of nasty if you like labels
  416.     with names like END.
  417.     The two xxxFormat options are mutually exclusive
  418. #endif
  419. #if OlafHashFormat
  420.     With this option an initial # (after optional initial spaces)
  421.     turns the next word into a directive/opcode.
  422.     A ^ skips more spaces and makes the next word a label.
  423. #endif
  424.  
  425. GENERAL:
  426.  
  427.     The label will be set to the current ORG/RORG either before or after
  428.     a pseudo-op is executed.  Most of the time, the label to the left of a
  429.     pseudo-op is the current ORG/RORG. The following pseudo-op's labels are
  430.     created AFTER execution of the pseudo-op:
  431.  
  432.     SEG, ORG, RORG, REND, ALIGN
  433.  
  434. EXTENSIONS:
  435.  
  436.     FORCE extensions are used to force an addressing mode.  In some cases,
  437.     you can optimize the assembly to take fewer passes by telling it the
  438.     addressing mode.  Force extensions are also used with DS,DC, and DV
  439.     to determine the element size.  NOT ALL EXTENSIONS APPLY TO ALL
  440.     PROCESSORS!
  441.  
  442.     example:    lda.z   charlie
  443.  
  444.     i   -implied
  445.     ind -indirect word
  446.     0   -implied
  447.     0x  -implied indexing (0,x)
  448.     0y  -implied indexing (0,y)
  449.     b   -byte address
  450.     bx  -byte address indexed x
  451.     by  -byte address indexed y
  452.     w   -word address
  453.     wx  -word address indexed x
  454.     wy  -word address indexed y
  455.     l   -longword (4 bytes) (DS/DC/DV)
  456.     r   -relative
  457.     u   -uninitialized (SEG)
  458.  
  459.     First character equivalent substitutions:
  460.  
  461.     b z d        (byte, zeropage, direct)
  462.     w e a        (word, extended, absolute)
  463.  
  464.  
  465. ASSEMBLER PASSES:
  466.     The assembler may have to make several passes through the source
  467.     code to resolve all generation.  The number of passes is not
  468.     limited to two.  Since this may result in an unexpected, verbose
  469.     option 2, 3, and 4 have been provided to allow determination of the
  470.     cause. The assembler will give up if it thinks it can't do the
  471.     assembly in *any* number of passes.
  472.  
  473.     Error reporting could be better....
  474.  
  475.  
  476. EXPRESSIONS:
  477.     [] may be used to group expressions.  The precedense of operators
  478.     is the same as for the C language in almost all respects.  Use
  479.     brackets [] when you are unsure.  The reason () cannot be used to
  480.     group expressions is due to a conflict with the 6502 and other
  481.     assembly languages.
  482. #if OlafBraKet
  483.     It is possible to use () instead of [] in expressions following
  484.     pseudo-ops, but not following mnemonics. So this works:
  485.     if target & (pet3001 | pet4001), but this doesn't:
  486.     lda #target & (pet3001 | pet4001).
  487. #endif
  488.  
  489.     Some expressions, such as ||, can return a resolved value even if
  490.     one of the expressions is not resolved.   Operators are as follows:
  491.  
  492.     NOTE WELL: Some operations will result in non-byte values when a
  493.     byte value was wanted.    For example:    ~1  is NOT $FF, but
  494.     $FFFFFFFF.  Preceding it with a > (take LSB of) will solve the
  495. #if OlafLt
  496.     (a < of course, and Matt means ~0 I take it.)
  497. #endif
  498.     problem.  ALL OPERATIONS ARE CARRIED OUT IN 32 BITS.
  499.  
  500.     prec        UNARY
  501.  
  502.     20  ~exp    one's complement.
  503.     20  -exp    negation
  504.     20  !exp    not expression (returns 0 if exp non-zero, 1 if exp zero)
  505. #if OlafLt
  506.     20  <exp    take LSB byte of an expression
  507.     20  >exp    take MSB byte of a 16 bit expression
  508.             If the -< option is given, these operators are swapped
  509.             back to their original (unconventional) meaning, below.
  510. #else
  511.     20  <exp    take MSB byte of a 16 bit expression
  512.     20  >exp    take LSB byte of an expression
  513. #endif
  514.  
  515.             BINARY
  516.  
  517.     19  *        multiplication
  518.     19  /        division
  519.     19  %        mod
  520.     18  +        addition
  521.     18  -        subtraction
  522.     17  >>,<<   shift right, shift left
  523.     16  >,>=    greater, greater equal
  524.     16  <,<=    smaller, smaller equal
  525.     15  ==        equal to.  Try to use this instead of =
  526.     15  =        exactly the same as == (exists compatibility)
  527.     15  !=        not equal to
  528.     14  &        logical and
  529.     13  ^        logical xor
  530.     12  |        logical or
  531.     11  &&        left expression is true AND right expression is true
  532.     10  ||        left expression is true OR right expression is true
  533.      9  ?        if left expression is true, result is right expression,
  534.             else result is 0.    [10 ? 20] returns 20
  535.      8  []        group expressions
  536.      7  ,        separate expressions in list (also used in
  537.             addressing mode resolution, BE CAREFUL!
  538.  
  539.     Constants:
  540.  
  541.     nnn    decimal
  542.     0nnn    octal
  543.     %nnn    binary
  544.     $nnn    hex
  545.     'c      character
  546.     "cc.."  string (NOT zero terminated if in DC/DS/DV)
  547.     [exp]d    the constant expressions is evaluated and it's decimal
  548.         result turned into an ascii string.
  549.  
  550.     Symbols:
  551.  
  552.     ..    -holds evaluated value in DV pseudo op
  553.     .name    -represents a temporary symbol name.  Temporary symbols
  554.          may be reused inside MACROS and between SUBROUTINES
  555.     .    -current program counter (as of the beginning of the
  556.          instruction).
  557.     name    -beginning with an alpha character and containing letters,
  558.          numbers, or '_'.  Represents some global symbol name.
  559. #if OlafStar
  560.     *    -synonym for ., when not confused as an operator.
  561. #endif
  562. #if OlafDol
  563.     nnn$    -temporary label, much like .name, except that defining
  564.          a non-temporary label has the effect that SUBROUTINE
  565.          has on .name.    They are unique within macros, like
  566.          .name.  Note that 0$ and 00$ are distinct, as are 8$
  567.          and 010$.
  568.          (mainly for compatibility with other assemblers.)
  569. #endif
  570.  
  571.  
  572. WHY codes:
  573.     Each bit in the WHY word (verbose option 1) is a reason (why
  574.     the assembler needs to do another pass), as follows:
  575.  
  576.     bit 0   expression in mnemonic not resolved
  577.     1   -
  578.     2   expression in a DC not resolved
  579.     3   expression in a DV not resolved (probably in DV's EQM symbol)
  580.     4   expression in a DV not resolved (could be in DV's EQM symbol)
  581.     5   expression in a DS not resolved
  582.     6   expression in an ALIGN not resolved
  583.     7   ALIGN: Relocatable origin not known (if in RORG at the time)
  584.     8   ALIGN: Normal origin not known    (if in ORG at the time)
  585.     9   EQU:   expression not resolved
  586.     10  EQU:   value mismatch from previous pass (phase error)
  587.     11  IF:     expression not resolved
  588.     12  REPEAT: expression not resolved
  589.  
  590.     13  a program label has been defined after it has been
  591.         referenced (forward reference) and thus we need another
  592.         pass
  593.     14  a program label's value is different from that of the
  594.         previous pass (phase error)
  595.  
  596.     Certain errors will cause the assembly to abort immediately, others
  597.     will wait until the current pass is other.    The remaining allow another
  598.     pass to occur in the hopes the error will fix itself.
  599.  
  600.  
  601.  
  602. End of DASM.DOC.
  603.